feat(swift-sdk): add Core wallet balance diagnostics - #4580

Correctness of what the export claims:

- Only report `unspent_with_confirmed_spending_transaction`. A TXO linked
  to a mempool spender while still unspent is what
  `reconcileSpendObservation` writes for every normal in-flight send, so
  the old rule put one warning per output on a healthy wallet.
- Match CoinJoin TXOs to the wallet the way the rest of the snapshot
  does (denormalized id OR relationship). Accepting only the
  relationship dropped exactly the rows whose relationship is corrupt.
- Count outputs the #4438 audit cannot attribute
  (`unattributed_output_count`, `output_address_undecodable_count`,
  `bip44_address_pool_size`) so a zero missing count is no longer read
  as proof for a wallet whose address rows are absent.
- Resolve duplicate outpoints deterministically instead of `rows.first`,
  which made `wrong_wallet` depend on SwiftData's fetch order.
- Emit `asset_lock_db_memory_diff_summary` with `diff_incomplete=true`
  when the Rust side fails, mirroring the database-unavailable path; an
  absent line is indistinguishable from a truncated log. Adds
  `memory_query_available` to all three paths.
- Key the memory side of the AssetLock diff through
  `PersistentAssetLock.encodeOutPoint` rather than a second hex loop.
- Report `unknown_previous_height` when the rescan checkpoint could not
  be read, and fold `requested >= previous` into `no_op` as
  `spvRescanFilters` documents.

Store opening:

- `DashModelContainer.open` falls back to inferred lightweight migration
  when the staged plan rejects the store. Only `PersistentAssetLock` is
  frozen so far, so a v4.2.0-dev.1 store matches no registered version
  and hosts turn the throw into a launch crash. Records the outcome as
  `migration_path` plus `core_store_staged_migration_failed`.
- Buffer up to 256 events emitted before the log sink exists and replay
  them on install. `core_store_open_result` runs in the host's `init()`
  and never reached the exported `swift/run.log`.

Cost on the launch path:

- `summarizeRestoreBuffer` is one pass over counters instead of ~15 full
  array passes, and no longer retains the emitted-candidate array.
- Keep only account-less rows in a side map rather than duplicating
  every unspent row into a second per-wallet bucket map.
- Run read-only diagnostic FFI reads on their own `.utility` queue
  instead of the lifecycle `destroyQueue`.

Tests and cleanup:

- `Dev1StoreUpgradeTests` drives `DashModelContainer.open` — the path
  that ships — and asserts the staged plan alone still rejects the
  fixture, on its own copy.
- The startup guard list uses the event names actually emitted;
  `core_db_memory_diff` never existed, so that guard could not fail.
- Drop the hardcoded `container_reused`, and share one saturating-sum
  rule via `diagnosticSaturatingAdd`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…bound the export

Round-2 review of the Core wallet diagnostics.

Store opening:

- `DashModelContainer.open` falls back to inferred migration only when the
  store existed before the open AND matches no schema `DashMigrationPlan`
  registers. The decision is made on the store — `storeMatchesRegisteredSchema`
  reads its metadata through `NSPersistentStoreCoordinator` and checks each
  registered `VersionedSchema`'s `NSManagedObjectModel` for compatibility —
  because the error SwiftData throws for Cocoa 134504 is the opaque
  `SwiftDataError.loadIssueModelContainer` with no underlying `NSError`, the
  same value a corrupt file produces. A store that matches a registered
  version and still failed (a future custom `MigrationStage`) is rethrown
  untouched, so the fallback can never stamp the current checksum on a store
  that skipped a stage. Unreadable metadata is rethrown too.
- `open(_:)` is public: DashWallet builds its own `ModelConfiguration` and
  never calls `create`, so without this none of the store-open telemetry or
  the fallback can reach it.
- `Dev1StoreUpgradeTests` pins the precondition (the fixture matches no
  registered version), the fallback, the rethrow of a corrupt file with no
  fallback attempted, and the self-heal: after the fallback the store
  matches a registered version and reopens through the staged path.

Export cost:

- `CoreDiagnosticRowLimits`: the export counts rows before materializing.
  Above 100k TXO rows or 20k transaction rows table-wide it narrows to the
  wallet's own rows, declines the exact #4438 audit, and reports
  `audit_incomplete=true, reason=tables_too_large_for_exact_audit` with the
  counts and limits. Not a fetch limit — a truncated table would collapse
  `wrong_wallet` into `missing_txo` — but an honest refusal where the exact
  pass is not computable. `core_db_wallet_snapshot` records `txo_scan_scope`.
- `emitCoreWalletDiagnostics(for:)` documents that it holds the persistence
  serial queue for its duration and blocks every Rust persister/SPV callback
  until it returns. The paged variant is #4607.

Audit correctness:

- The representative row is judged by the same rule that admitted it
  (`denormalized || relationship`). Ours by id with a nil link reports
  `relationship_missing`; ours by id with a link elsewhere reports
  `wallet_id_mismatch` — the vocabulary `logTxoAnomalies` already uses.
  `representativeTxo` prefers by the same rule.

Tests:

- `SDKLoggerPreInstallBufferTests`: replay order, debug filtering at replay,
  overflow drops the oldest and reports the count, second install replays
  nothing. On a fresh `SDKLoggerState`, since the singleton has no way back
  to "no sink".
- DB/memory AssetLock key pairing through one encoder; malformed txid neither
  traps nor collides.
- `representativeTxo` on transient rows (`outpoint` is unique, so a
  duplicate cannot be saved through a context).
- Unattributed-output and undecodable-address counters; the broken-link
  classification.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

`walletOwnsTransaction` faults four relationships per transaction
cross-wallet, each a query under the coordinator lock, so the transaction
count — not decoding — decides how long the export holds the persistence
queue. 20k was a guess; 10k keeps the exact #4438 audit on ordinary wallets
while bounding the worst case to a few seconds rather than tens. The paged
variant (#4607) is what lifts this properly.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…ound-3 diagnostics review

Store opening:

- `classifyStore(at:)` replaces the `Bool?` check with a verdict, and the
  inferred-migration fallback runs only for `driftedRegisteredVersion`. A
  store from a newer build — a `VersionedSchema` identifier this plan never
  registered (SwiftData writes them into `NSStoreModelVersionIdentifiers`),
  or an entity the current schema lacks — is `newerThanRegistered` and is
  rethrown: inferred migration would open it and drop what the newer build
  wrote without a word, which is worse than the crash it replaced.
  Unreadable stores and stores that match a registered version but failed
  anyway are rethrown too. `store_verdict` is logged on both events. The
  residual (a newer build that only added an attribute and kept the
  identifier looks like drift) is documented on `classifyStore`; freezing
  the remaining shapes is what closes it.
- `open(_:)` refuses a configuration whose `Schema` differs from the SDK's
  (`DashModelContainerError.schemaMismatch`) instead of silently building
  the container for the SDK schema anyway; the configuration contributes
  URL and options only, and the doc says so.
- `fileSize(at:)` reads through a fresh URL so the after-open size is not
  `NSURL`'s cached before-open value.

Audit correctness:

- Stub transactions (empty `transactionData`, a real production state) are
  counted into `transaction_bytes_missing_count` and make the audit
  incomplete instead of being skipped before decoding.
- `accountOrder` is the one comparator for every per-account pass, so the
  BIP44 account that wins a duplicated address is the same on every export.
- `duplicateResolutionKey` includes the account identity, so rows differing
  only by account no longer tie in an unstable sort.
- Restore rows no wallet can claim are counted and reported once in
  `core_restore_unroutable_rows`.
- A rescan request rejected for a bad wallet id now logs
  `core_rescan_armed result="invalid_wallet_id"` like every other exit.

Lifecycle:

- `shutdown()` raises `coreDiagnosticsCancellation` before draining the
  diagnostics admission; the off-main pass checks it before every FFI read
  and returns, so the drain waits for at most the read already in flight.

Cost on the held queue:

- One grouped pass per wallet replaces the per-account identity filter and
  five filters per account.
- The two transaction counts come from `wallet.accounts.involvedTransactions`
  instead of `walletOwnsTransaction` over every row (four faults each);
  fields renamed `involved_transaction_count` /
  `involved_type_8_transaction_count` to say which relation they follow.
- Anomaly counts per reason are computed once from the existing grouping.

Cleanup:

- The always-`.preExport` `checkpoint` parameter is gone from the database
  diagnostics entry points, with its dead arms; the static helpers keep it
  because they also serve the restore-path event.
- `readAccountBalances(handle:walletId:)` is the one FFI reader;
  `accountBalances(for:)` wraps it and the diagnostics' copy is deleted.
- `SDKLogger.resetForTesting()` lets every suite that asserts over a whole
  `run.log` start from an empty backlog regardless of test order.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

… have drifted

A newer build that adds an attribute to an existing entity and keeps its
version identifier leaves a store with the same entity names as ours and
one differing hash — which, to the version-identifier and unknown-entity
checks, looks exactly like a drifted v4.2.0-dev.1 store. The fallback then
opened it with inferred migration and dropped the attribute's values.

`classifyStore` now compares the store's per-entity hashes against the
model of the version the store declares, and the fallback runs only if
every disagreeing entity is in `knownDriftedEntities`: the two shapes
changed in place since V1 (`PersistentDocumentType`, `PersistentIndex`),
which is why a dev.1 store fails its checksum at all. A disagreement
anywhere else is `newerThanRegistered(reason: "unexpected_entity_drift=…")`
and is rethrown, with the verdict on the failure event.

The decision is a pure function (`storeSchemaVerdict`) so every branch is
tested on plain values; `testKnownDriftedEntitiesArePinnedToTheFixture`
asserts the allowlist equals the fixture's actual disagreeing set, so it
cannot be wider than reality and shrinks as shapes get frozen; and
`testStoreWithAnAttributeOnlyNewerEntityIsRefusedWithoutFallback` writes a
real store through a `VersionedSchema` that keeps V3's identifier and clones
`PersistentWalletManagerMetadata` with one extra attribute, then asserts it
is refused untouched.

What remains, stated on `storeSchemaVerdict`: a newer build that changed
only one of those two already-drifted entities still reads as drift. That
is as narrow as metadata allows; freezing the two shapes removes it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

`DashModelContainer.open` refuses a store written by a newer build rather
than opening it with inferred migration, which would drop what that build
wrote. Until now the refusal rethrew SwiftData's opaque
`loadIssueModelContainer`, which a host cannot tell from a corrupt file —
so it had nothing to say to the user beyond "setup failed".

It now throws `DashModelContainerError.storeFromNewerBuild(reason:)`, with
an `errorDescription` that says what happened and the two ways forward
(update the app, or reset the wallet). Unreadable stores, and stores that
match a registered version but failed anyway, still rethrow SwiftData's
own error untouched. The Dev1 tests pin the typed error for both newer
cases and its absence for the corrupt-file case.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…tate only, drop the rescan label

Round-4 review of the Core wallet diagnostics.

Shutdown and cancellation:

- Admission is taken BEFORE the database half and released after the Rust
  half, so `shutdown()`'s drain covers the whole export. A teardown that
  began during the cross-wallet scan used to proceed while that scan still
  held the persistence queue every persister callback enters through.
- The queue-confined pass takes the cancellation token and checks it
  before the TXO fetch, the transaction fetch and the owned-output audit,
  logging what it skipped (`core_diagnostics_unavailable
  reason=shutdown_requested skipped_from_stage=…`, or an
  `audit_incomplete` summary at the audit stage) and returning. The drain
  now waits for at most the stage in flight, on either half.

Database pass:

- Runs on a scratch `ModelContext(modelContainer)` created inside the
  `serialQueue.async` block. It sees only COMMITTED state — a Rust
  `store()` round is one changeset across several separate `sync` blocks,
  and the pass can land between two of them, where the handler's own
  context holds pending rows `endChangeset` may still roll back — and it is
  dropped with the block, so the up-to-110k objects it registers do not
  stay resident for the life of the process. The queue still guarantees
  no save lands mid-pass. `backgroundContext` and `onQueue` are private
  again; the `onQueue` doc that claimed the opposite is gone.
- A missing database snapshot (wallet row absent, fetch failed — the very
  "coins gone from the database" reports this is for) no longer suppresses
  the Rust half. It runs on the wallet id alone, and both diffs mark the
  one-sided case with `database_snapshot_available=false` rather than
  going silent.

Logging:

- The pre-install buffer keeps its head and drops the newest arrival once
  full. The store-open line from the host's `init()` is the first in and
  the one the buffer exists to carry; overflowing with restore and
  changeset lines must not evict it.

Rescan:

- `core_rescan_requested` records what was asked and whether the FFI
  accepted it (`accepted` / `failed` / `invalid_wallet_id`). The
  pre-call `coreWalletState(for:)` — a Rust-lock FFI read on the main
  actor, added for a log field — is gone, and so is the rewind label it
  fed: it compared against the core wallet's synced height, not the
  filter-scan checkpoint the rescan lowers, so an armed rescan could log
  `no_op`. The classifier and its test go with it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

`storeSchemaVerdict` returned `driftedRegisteredVersion` — the one verdict
that authorizes inferred lightweight migration — for a store whose metadata
carried no entity hashes at all: nothing disagreed because nothing was
compared, and the store would have been opened by inference and trimmed to
the current schema. Drift now requires at least one entity actually
compared and at least one actually disagreeing.

Stores that cannot be placed no longer borrow the newer-build error either.
`no_version_identifier` is an old or truncated store as much as a new one,
and `storeFromNewerBuild` tells the user to update the app or reset the
wallet — destructive advice on a store that is fine. A new `.unplaceable`
verdict rethrows SwiftData's own error instead, with the verdict in the log.

`shutdown()` raised the diagnostics cancellation after the handle guard, so
a pass running for a never-configured manager — the branch that deliberately
runs its database half without a handle — could not be told to stop, and
held the persistence queue across teardown. Cancel before the guard.

The #4438 audit reported a clean, complete result when the persisted BIP44
address pool was empty: every output fell through as unattributed and
nothing reached the missing-TXO check, on exactly the wallet whose address
rows went missing. An empty pool is now an incompleteness like an
undecodable transaction. Deliberately not `unattributed_output_count > 0`:
a CoinJoin transaction pays its peers, so every healthy audit has some.

Also: an autorelease pool per account in the memory half, matching the
database half — the whole loop is one GCD work item, so the peak was the sum
of every account rather than the largest; and the restore snapshot no longer
classifies every row on the errored path, where it faulted a relationship
per row, at launch, under the queue, to describe a load being discarded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ection

A hash disagreement is symmetric — it says the store's shape of an entity is
not the live model's, not which came first. V1/V2/V3 are unfrozen, so adding
one attribute to any live model makes every EXISTING store disagree on that
entity: an older store, reported as a newer one, with "reset the wallet" as
the offered remedy. An unregistered version identifier is ambiguous the same
way (pre-V1, or a version since dropped from the plan). Both become
`.unplaceable`, which rethrows SwiftData's own error. The one asymmetric
fact left — the store carries an entity this schema does not have — keeps
`newerThanRegistered`, and with it the only honest "update the app".

Last round's cancellation fix overshot: latching above the handle guard also
latched on the guard's deliberately uncached no-op return, so a manager built
and shut down before `configure()` could never produce a support export
again. The latch is now as conditional as the state it accompanies — a live
handle, or a pass actually in flight, counted for both halves.

The flag was also polled at only three points, so `shutdown()`'s drain could
wait for the whole-wallet fingerprint, the per-account snapshots and
`logTxoAnomalies` — the stages that dominate the queue hold. Each is gated
now, and the audit's check no longer hides inside `if let allTransactions`,
where it was skipped exactly when the audit had already been declined.

The #4438 audit knew only BIP44 addresses, so a mixed send's own CoinJoin
change was booked as "unattributed" — documented as peers' outputs — and a
CoinJoin-side output missing from PersistentTxo was invisible: a third route
to the false all-clear. The pool now covers CoinJoin accounts, the account
check compares against the account the pool named, and the missing counts
are reported per side.

Also: every early return out of the memory half now emits its
`diff_incomplete=true` summary, since an absent summary reads as a truncated
log; and the export entry point documents that its only caller is the host
app, by design.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The native-op admission exists to keep `handle` alive while an FFI read is in
flight. The database half makes no FFI call — it reads SwiftData on the
persistence serial queue — so covering it bought the handle nothing and cost
`shutdown()`'s drain everything: the drain would wait on a block whose
progress depends on that queue, and a wedged persister round is exactly when
that queue does not advance. There is no deadline on the drain.

Ordering does not come from the drain and survives without it. Native
teardown runs on `destroyQueue`, and the Rust destroy's persister callbacks
enter through `serialQueue.sync`, so they queue behind the scan rather than
racing it — off the main thread, and bounded by the cancellation flag the
scan polls between stages. ARC covers the object lifetimes: the block holds
the handler and its container, so neither can be deallocated under the read.

Admission is therefore back around the FFI half only, which runs on
`coreDiagnosticsQueue` and polls cancellation between reads, so the drain
waits on a stage this manager owns. The cancellation flag still covers the
whole pass, and that — not the drain — is what closes the gap where a
database half running for a manager with no handle could not be told to stop.

This is the third time this admission has moved, so the reasoning is now in
the code beside it rather than only in review.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…has a direction

The last route to `newerThanRegistered` was an entity the current schema
lacks. That looks identical whether a newer build added it or an older build
wrote one since renamed — and this SDK performed exactly such a rename,
`PersistentUtxo` to `PersistentTxo`, documented a few hundred lines below the
check. So the oldest stores in existence were the ones being told they came
from the future, with a wallet reset offered as the remedy.

There is no observable here that carries direction, so the verdict no longer
claims one: everything unplaceable is `unplaceable`, and
`DashModelContainerError.storeFromNewerBuild` is gone with its message. The
refusal is unchanged — inferred migration is still never offered, which is
what protects the data — only the explanation the host could act on
destructively.

The audit's own loops now poll cancellation, not just the stages around them.
It is the most expensive stage in the pass (up to 10k decodes plus per-output
relationship work), so a shutdown arriving mid-loop no longer waits for all
of it; the audit reports that it gave up and the pass abandons the rest.

And the empty-pool incompleteness check covers CoinJoin too. Widening
`ownedAddresses` to CoinJoin accounts last round while leaving the check on
BIP44 alone had opened a fourth route to the false all-clear: a lost CoinJoin
address pool, on precisely the mixed wallet this audit exists for. Guarded on
there being CoinJoin accounts at all, so an unmixed wallet is not flagged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ve filled it

The empty-pool check judged BIP44 unconditionally, so a CoinJoin-only wallet
reported `audit_incomplete=true` although attribution had worked — noise in
the one field an analyst uses to decide whether to keep reading. It is now
symmetric: a pool counts as evidence only when there are accounts that should
have filled it, plus an unconditional clause for owning no addresses at all,
where nothing can be attributed however few accounts exist.

`bip44_address_pool_empty` is renamed `address_pool_empty` to match what it
now covers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>